What You need

In order to use these tools you will need to have RStudio and to have installed the natverse. To use them to maximum effect, you will need to also have permission to access the FAFB CATMAID v14 project, although some neurons are available to be read by the public from Virtual Fly Brain’s CATMAID project for FAFB and should have the same unique skeleton ID numbers. Our pipeline function makes use of the Google Filestream application, which should be installed on your machine. Further, note that neurons are read from the FAFB CATMAID project, and you must have login details for this project recorded in your .Renviron (edit with: usethis::edit_r_environ) for these functions to work. For help, see here.

Authorisation

In order to write neuron matches to the project you must have access to the hemibrain Google Drive or the match making Google sheet (see below) owned by the Drosophila Connectomics Group. If you do not have access but would like to help or use this information, get in contact! You do not need programming skills to to help us match make neurons, as we have written an interactive pipeline in R which does most of the work for you (see below).

We regularly also up-date a data frame saved in this package, as a snapshot of matches that have been made. Without authorisation you can access these matches but they may not be the most up-to-date:

# Load package
library(hemibrainr)
# See matches
View(hemibrain_matched)

The Google Sheet

We in the Drosophila Connectomics Group have been recording our match making in a Google sheet named em_matching. This sheet has two tabs of concern here, hemibrain for hemibrain neuron -> FAFB neuron matches and fafb for FAFB neuron to hemibrain neuron matches.

google_sheet

If you have authorisation, you can see the most up-to-date matches as so:

matches = hemibrain_matches() # You will be asked to log-in through a Google-enabled email address.
View(matches())

As you can see, other meta information is present in the data frame matches. The function hemibrain_matches has an argument called priority. This specifies whether to use FAFB->hemibrain matches (FAFB) or hemibrain->FAFB matches (hemibrain) in order to ascribe cell type names to FAFB neurons. In both cases, cell type names are attached to hemibrain bodyids, and propagated to their FAFB matches.

Match Quality

Once a match is recorded, the user selects a quality for that match. There can be no match (none), a tract-only match (tract) a poor match (poor) an okay match (medium) or an exact match (good). As a rule of thumb, a poor match could be a neuron from a very similar same cell type or a highly untraced neuron that may be the correct cell type. An okay match should be a neuron that looks to be from the same morphological cell type but there may be some discrepancies in its arbour. A good match is a neuron that corresponds well between FAFB and the hemibrain data.A tract only match just means that the matched neuron should share the same cell body fiber, and therefore same developmental ontogeny, even if the rest of its morphology is quite different.

It is very important to note that a match cannot be a match if neurons do not seem to share the same cell body fiber tract. Being in a different tract is a deal breaker.

Some good matches are striking. For example:

good_match_1

In the above case, the FAFB neuron has been quite extensively manually traced, meaning that these cells look very similar to one another.

Be aware that while neurons must share the same cel lbody fiber tract, these tracts can be a little off set. For example, this is also a good match:

good_match_2

If the some is missing, it might be safer to note a match as ‘medium’.

You might also use medium if you have a nice looking match and suspect that there is a medium/large discrepancy because the FAFB neuron (here shown in red) is under-traced, such as:

medium_match_2

Or:

Bear in mind that the hemibrain volume only covers ~1/4 of the fly mid-brain, so neurons are trunacted (here hemibrain neuron in black) but we can still make matches for many of them:

medium_match_4

A larger degree of under-tracing may lead you to assign a match as poor. In this case, you think the two neurons may be ‘the same isomorphic cell type’ but you could be wrong. For example:

poor_match_1

A poor match may also be made if you think these is a slight offset, possibly due to a registration issue:

poor_match_2

Though in this case, choosing a even lesser-traced FAFB neuron may be better:

poor_match_3

A poor match can be given even to very under-traced FAFB neurons:

poor_match_4

And even fragments if you are convinced the morphology is unique enough (but be careful!):

poor_match_5

Adding Your Own Matches

So far we have matched up a few thousand neurons. About 25 thousand matches are possible because that is the number of reconstructed neurons in the hemibrain data set. You can help us (and yourself!) by adding matches to our database. There are two main ways of doing this:

made.matches = read.csv("my_matches.csv") # Must have the named columns: bodyid, skid, quality
hemibrain_matches(df = made.matches, direction = "both") # direction controls which tabs matches get written to

# Add a mising FAFB projection neuron, so we can match it later:
hemibrain_matching_add(ids = "16", sheet = "fafb", User = "ASB")
## the sheet argument specifies the worksheet or 'tab' on the Google sheet we want to add to

The Match Making Pipeline

You can also use our interactive pipeline to match neurons between hemibrain and FAFB. There are two version of this pipeline. One that takes hemibrain neurons from neuPrint, and tries to find the best match for each hemibrain neuron (hemibrain_matching) and one that takes FAFB neurons from CATMAID and tries to find the best heimibrain match for those FAFB neurons (fafb_matching). Once matches are made, the result become available with hemibrain_matches.

For a video tutorial, see here.

# install package to bridge neurons between FAFB14 and hemibrain space
if (!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github('natverse/nat.jrcbrains')
nat.jrcbrains::download_saalfeldlab_registrations()

# Match hemibrain neurons!
hemibrain_matching() # Automatically, you can choose a User ID and you are given neurons that have this ID in the User column on the Google Sheet.
hemibrain_matching(ids=c("674108632","739256609")) # Otherwise you can select specific IDs
hemibrain_matching(ids=c("674108632","739256609"), overwrite = TRUE) # If a match has already been made you can overwrite it
# Otherwise neurons that have already been given a match will not be shown in the pipeline.

# Match FAFB neurons!
fafb_matching()
fafb_matching(ids = "16") # Specify IDs
fafb_matching(ids = "16", overwrite = TRUE) # Overwrite

When you run these functions you will enter an interactive pipeline in an rgl window. Prompts will be given to you in your R console and you can rotate and pan in the window to see neurons. The neuron selected for-matching is shown in black (i.e. if using hemibrain_matching this will be a hemibrain neuron), and potential matches in colour (i.e. if using hemibrain_matching these will be FAFB neurons). Potential matches are shown by NBLAST score (a measure of morphological similarity). Usually, for reasonably traced FAFB neurons, a good match appears in the top 10 hits.

pipeline_console

Uses

One use we have already found for all of this match making, is to cross-identify neuron cell body fiber tracts and (hemi)lineages. This means that we now have the locations in FAFB for different known sets of cells. You can see seed planes for them here.

google_sheet_lineages